home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d1 / clipasc.arc / CLIPASC.DOC < prev    next >
Text File  |  1987-03-17  |  10KB  |  330 lines
  1.  
  2.                 CLIPASC
  3.             ASCII File Access From Clipper
  4.                   Version 1.1
  5.  
  6.              Written by Ben Cohen
  7.  
  8.  
  9.     CLIPASC is a set of User Defined functions, programmed in Assembler
  10. which allow a program written in Clipper to access and manipulate
  11. information contained in flat ASCII files.
  12.  
  13. Files in this package:
  14.  
  15.     CLIPASC.ASM    Source code for CLIPASC
  16.     ASCSCAN.MAC    Macro definitions for CLIPASC
  17.     CLIPASC.OBJ    Compiled version of CLIPASC
  18.     CLIPASC.DOC    This document
  19.  
  20.     Since CLIPASC was written as part of a project for Irving Trust
  21. Company, I am unable and unwilling to request any payment for this
  22. function package. However, I appreciate it if people would let me know
  23. about any problems that you encounter while using CLIPASC. In addition,
  24. I would like any suggestions for upgrades to be made to CLIPASC. While
  25. writing it, I made sure that it had all of the functionality that I
  26. required, but there may be more lurking out there that is still needed.
  27.  
  28. Please address any correspondence to:
  29.     Ben Cohen
  30.     12 Britton St.
  31.     Jersey City, NJ  07306
  32.     Re:  CLIPASC
  33.  
  34.     I make no promises that I will fix all errors that are presented,
  35. although I will try. In addition, I make no claims that any suggestions
  36. will be implemented. My time is limited and this was written out of
  37. necessity. And, lastly, both CLIPASC and myself are not in any way,
  38. shape, or form responsible for any damage that may result from the use
  39. of CLIPASC. Use this at your own risk.
  40.  
  41.     And, now for the good stuff:
  42.  
  43.  
  44.                  Using CLIPASC
  45.  
  46.     CLIPASC consists of 8 functions that all work together to read and
  47. write files, although they work at different levels.
  48.  
  49.  
  50.  
  51. OPENASC():
  52.  
  53.     OPENASC will open a file in a specified read/write mode. It
  54.     returns the file handle that was returned by DOS which is used for
  55.     all future file operations.
  56.  
  57.  
  58.     The syntax for OPENASC is:
  59.  
  60.     OPENASC(name,mode)
  61.  
  62.     Where: name - fully expanded file name and extension
  63.            mode - file mode to use. Possible modes are:
  64.               r   - file is read only. Positioned at
  65.                 beginning of file.
  66.               w   - file is write only. If file exists, it
  67.                 is truncated. Otherwise, it is created.
  68.               r+  - file is read only. Positioned at end
  69.                 of file.
  70.               w+  - file is write only. Positioned at end of
  71.                 file, if file exists. Otherwise, file is
  72.                 created.
  73.               rw  - file is read/write. Positioned at
  74.                 beginning of file, if file exists.
  75.                 Otherwise, file is created.
  76.               rw+ - file is read/write. Positioned at end of
  77.                 file, if file exists. Otherwise, file is
  78.                 created.
  79.  
  80.     Return values:
  81.     -1 = indicates error. Use ASCRETCD() to get error code.
  82.     Any other returned value is the file handle. This number must
  83.           be retained for all future file accesses.
  84.  
  85.  
  86.  
  87. CLOSEASC():
  88.  
  89.     CLOSEASC will close a previously opened file so that it is no
  90.     longer able to be used. This will also release the file handle that
  91.     was associated with the file so it might be reused by a different
  92.     file.
  93.  
  94.  
  95.     The syntax for CLOSEASC is:
  96.  
  97.     CLOSEASC(handle)
  98.  
  99.     Where: handle  - file handle that was returned from OPENASC.
  100.  
  101.     Return values:
  102.      0 = no error. File closed ok.
  103.     -1 = error. Use ASCRETCD() to get error code.
  104.  
  105.  
  106.  
  107. LINEIN():
  108.  
  109.     LINEIN reads a sequence of characters from a specified file up
  110.     through and past the first CR-LF sequence encountered in the file.
  111.     This string is then returned to Clipper and your program.
  112.  
  113.  
  114.     The syntax for LINEIN is:
  115.  
  116.     LINEIN(handle)
  117.  
  118.     Where: handle  - file handle that was returned from OPENASC.
  119.  
  120.     Returns:
  121.     null string = indicates possible error. Check ASCRETCD() to be
  122.         certain. If ASCRETCD() = 0, no error occured, just an
  123.         empty line. Also, if ASCRETCD() = -1, EOF has been
  124.         reached.
  125.     otherwise, next CR-LF delimited line is returned.
  126.  
  127.     Note:
  128.     Lines from the file must be no greater than 512 bytes or else you
  129.     will receive an error and a possible loss of data. Since most data
  130.     that is worked with has line lengths below about 150, this was
  131.     not deemed to be a very bad problem.
  132.  
  133.  
  134.  
  135. LINEOUT():
  136.  
  137.     LINEOUT will write a string to a file after appending a CR-LF
  138.     to the end of the string so that it will appear as a regular 'line'.
  139.  
  140.  
  141.     The syntax for LINEOUT is:
  142.  
  143.     LINEOUT(handle,string)
  144.  
  145.     Where: handle  - file handle that was returned from OPENASC.
  146.            string  - a string variable from Clipper. This string
  147.              must be no greater than 512 bytes or else it
  148.              will not be written.
  149.  
  150.     Returns:
  151.      0 = no error. Line written
  152.     -1 = indicates error. Use ASCRETCD() to get error code.
  153.  
  154.  
  155.     Designers Note:
  156.     I'd considered adding support so that CLIPASC could write out
  157.     the full string and then just write out the CRLF when it was done.
  158.     I decided against this method for ease and consistency. If there
  159.     is enough demand for this, I may again consider implementing it.
  160.     However, how many people really use ASCII files greater than 512
  161.     bytes wide?
  162.  
  163.  
  164.  
  165. CHARIN():
  166.  
  167.     CHARIN will read a specified number of characters from a file.
  168.     This read will be performed with no CR-LF translation whatsoever, so
  169.     you will get the bytes directly from the file.
  170.  
  171.  
  172.     The syntax for CHARIN is:
  173.  
  174.     CHARIN(handle[,count])
  175.  
  176.     Where: handle  - file handle that was returned from OPENASC.
  177.            count   - optional count of characters to read from file.
  178.              If not specified, count defaults to 1 character.
  179.              Count must be 512 or less.
  180.  
  181.     Returns:
  182.     null string = indicates error. Use ASCRETCD() to get error code.
  183.         If ASCRETCD() = -1, EOF has been reached.
  184.     Otherwise, the characters read from handle are returnde.
  185.  
  186.  
  187.  
  188. CHAROUT():
  189.  
  190.     CHAROUT will write a string out to the specified handle without
  191.     appending a trailing CR-LF. CHAROUT can also be used for file
  192.     truncation.
  193.  
  194.  
  195.     The syntax for CHAROUT is:
  196.  
  197.     CHAROUT(handle[,string])
  198.  
  199.     Where: handle  - file handle that was returned from OPENASC.
  200.            string  - character string to be written to the file. If
  201.              string is null, the file will be truncated at
  202.              the current file pointer.
  203.  
  204.    Returns:
  205.      0 = no error. String written.
  206.     -1 = error. Use ASCRETCD() to get error code.
  207.  
  208.  
  209.  
  210. ASCLSEEK():
  211.  
  212.     ASCLSEEK implements the DOS LSEEK function which allows change
  213.     of position within a file.
  214.  
  215.     The syntax for ASCLSEEK is:
  216.  
  217.     ASCLSEEK(handle[,[method][,offset]])
  218.  
  219.     Where: handle  - file handle that was returned from OPENASC.
  220.            method  - corresponds to the three types of movement for
  221.              LSEEK: from beginning of file, from end of file,
  222.              and from current position in file. Possible
  223.              methods are:
  224.                 b|B - offset is from beginning of file.
  225.                 c|C - offset is from current position
  226.                       in file.
  227.                 e|E - offset is from end of file.
  228.              If method is not specified, it defaults to 'c',
  229.              which is offset from current position in file.
  230.            offset  - optional distance to move within file. Offset
  231.              is invalid if method is 'e' (from end of file).
  232.              If not specified, offset defaults to 0, meaning
  233.              no offset.
  234.  
  235.     Return values:
  236.     -1 = error. Use ASCRETCD() to get error code.
  237.     Otherwise, returned value corresponds to the pointer position
  238.         in the file.
  239.  
  240.  
  241.  
  242. ASCRETCD():
  243.  
  244.     ASCRETCD will give you the return code of the last function from
  245.     the CLIPASC function package that was called, with the exception of
  246.     ASCRETCD itself. ASCRETCD can be called multiple times and will
  247.     return the same value each time until another function from CLIPASC
  248.     is called.
  249.  
  250.     The syntax for ASCRETCD is:
  251.  
  252.     ASCRETCD()
  253.  
  254.     Return values:
  255.      0 = indicates that last operation was successful.
  256.     Otherwise, value is from the following selections:
  257.  
  258.     4096 - 8191 = DOS error codes offset by 4096. Therefore, DOS
  259.               error code 1 is equivalent to 4097. The more likely
  260.               return codes are:
  261.  
  262.            4098 = File not found
  263.            4099 = Path not found
  264.            4100 = No handles left
  265.            4102 = Invalid handle
  266.  
  267.     8192 = Invalid number of parameters passed to the function.
  268.  
  269.     8200 - 8300 = Error in one of the passed parameters. The offset
  270.            from 8200 indicates which parameter was in error. For
  271.            example, 8201 indicates that the first parameter was in
  272.            error.
  273.  
  274.     8301 = Invalid mode used when opening a file.
  275.  
  276.     8401 = Invalid method used for ASCLSEEK on a file.
  277.  
  278.  
  279.                CLIPASC Examples
  280.  
  281.     The following code fragment will open two files and copy one file to
  282. the other with no error checking other than EOF. The input and output
  283. file names are in the variables FILE1 and FILE2 respectively.
  284.  
  285.     handle_1 = openasc(file1,'r')   && open for reading
  286.     handle_2 = openasc(file2,'w')   && create for writing
  287.     do while .T.
  288.        input = linein(handle_1)    && read a line
  289.        if ascretcd() = -1        && EOF?
  290.           exit
  291.        endif
  292.        x = lineout(handle_2)    && write it out and throw away
  293.                     && the return value
  294.     enddo
  295.     x = closeasc(handle_1)        && close one file
  296.     x = closeasc(handle_2)        && close the other
  297.  
  298.  
  299.     The following will read in the input file one character at a time,
  300. searching for 0xFE. When 0xFE is found, the next 10 bytes will be
  301. skipped over. All other input information will be written to an output
  302. file. The input and output file handles are in handle_i and handle_o
  303. respectively:
  304.  
  305.     do while .T.
  306.        input = charin(handle_i)    && default to one character read
  307.        if ascretcd() = -1        && EOF?
  308.           exit
  309.        endif
  310.        if input = chr(254)        && 0xFE?
  311.           x = asclseek(handle_i,'c',10)
  312.        else
  313.           x = charout(handle_o,input)
  314.        endif
  315.     enddo
  316.  
  317.  
  318.                 Change History
  319.  
  320. Version 1.1 - minor fixes from original (v1.0)
  321.  
  322.     Rewrite of return sections so that ES and BP restored before
  323.     calling _retxx functions. This may have caused some problems, but
  324.     none that exhibited themselves.
  325.  
  326.     Change combine class of code segment to 'PROG'. This forces the
  327.     linker to include it in before any of the library modules get
  328.     linked in. This prevents the code from getting overwritten at
  329.     runtime, which was happening with a combine class of 'CODE'.
  330.